Skip to content

feat(harness): PR-title CI lint, contexts/docs boundary, commit-body rule, and repo-root-relative refs#138

Merged
keli-wen merged 3 commits into
masterfrom
feat/harness-close-134-pr-title-and-boundary
Jul 23, 2026
Merged

feat(harness): PR-title CI lint, contexts/docs boundary, commit-body rule, and repo-root-relative refs#138
keli-wen merged 3 commits into
masterfrom
feat/harness-close-134-pr-title-and-boundary

Conversation

@keli-wen

@keli-wen keli-wen commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Finishes the harness work in #134: the last open acceptance criterion (the contexts/ vs docs/ boundary) plus the server-side floor for the commit convention, and it codifies the commit-body wrapping rule we agreed on.

  • PR-title CI lint.github/workflows/pr-title.yml lints the PR title (which becomes the squash-merge commit subject) as an English Conventional Commit, reusing scripts/hooks/commit_msg_check.py so the rule has a single source. The local commit-msg git hook only fires for contributors who ran pre-commit install, so it cannot bind external contributors; this workflow is the server-side floor that does. Making it a required status check is a one-time repository-settings toggle, separate from this PR.
  • contexts/ vs docs/ boundarycontexts/README.md now states it explicitly under "Where Information Lives": contexts/ is internal navigation and design memory for coding agents and maintainers; docs/ is the user-facing catalog (docs/README.md) and usage guides (docs/library.md). This was the one unmet acceptance criterion in feat(harness): agent-facing context map + convention-enforcing git hooks #134.
  • Commit-body wrap rulecommit.md (both skill copies) adds the convention: a commit body follows the same no-hard-wrap prose rule as GitHub bodies, so a squash-merge keeps a clean description. This PR's own commit body follows it.
  • Doccontexts/dev/harness-engineering.md records the PR-title lint in the enforcement table and replaces the earlier "planned next" note.
  • Repo-root-relative cross-references — nested skill files (SKILL.md, pull-request.md, commit.md) referenced contexts pages with deep, fragile links like ../../../../contexts/dev/github-writing.md. A bare clickable relative link only resolves against the current file's directory, so a nested file needs that ../ chain to stay clickable; the sister repo llmquant-data-mono avoids it by using repo-root-relative backtick references (contexts/...) from nested files. This PR adopts the same convention: nested files use backtick repo-root references, while root-level files (AGENTS.md) and sibling contexts pages keep their clean clickable links. tests/test_contexts.py now asserts the reference in the form appropriate to each source location plus repo-root existence, instead of a specific deep relative path.

Related Issue

Closes #134.

Verification

  • bash scripts/verify.sh passes: ruff format + ruff check + basedpyright + import-linter + pytest --cov (426 passed, 85.65% coverage). The two commit.md copies stay identical, and the edited contexts/ pages keep their required structure — both enforced by tests/test_contexts.py.
  • The reused rule was smoke-tested against a sample PR title, and pr-title.yml was validated as YAML. The workflow itself runs on GitHub against a pull request, so its end-to-end behavior is exercised by this PR's own title check rather than locally.
  • No live-network component smoke test applies: this PR adds a CI workflow, a documentation boundary, and a commit convention; it changes no public operation or source.

Checklist

  • The title uses English Conventional Commit format: type(scope): summary.
  • The related issue or design discussion is linked when applicable.
  • bash scripts/verify.sh passes.
  • Every applicable live-network component smoke test passes, or this PR states why none applies.
  • Public behavior has focused tests, an example, and documentation where applicable.
  • The PR is complete, small, and contains no unrelated changes.

…it-body wrap rule

Completes the remaining #134 work.

- .github/workflows/pr-title.yml lints the PR title (which becomes the squash-merge commit subject) as an English Conventional Commit, reusing scripts/hooks/commit_msg_check.py so the convention keeps one source. This is the server-side floor for external contributors, whom the local commit-msg git hook cannot bind because it only fires after `pre-commit install`.
- contexts/README.md now states the contexts/ vs docs/ boundary explicitly: contexts/ is internal navigation and design memory for agents and maintainers; docs/ is the user-facing catalog and guides. This was the last open acceptance criterion in #134.
- commit.md (both skill copies) adds the commit-body convention: follow the same no-hard-wrap prose rule as GitHub bodies, so a squash-merge keeps a clean description. This commit message follows it — one physical line per list item.
- contexts/dev/harness-engineering.md records the PR-title lint in the enforcement table and notes that making it a required status check is a one-time repo-settings toggle.

verify.sh passes (426 passed, 85.65% coverage).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@keli-wen keli-wen added type: feature Adds a new capability or observable behavior area: harness Contributor and agent controls, CI, hooks, skills, and rulesets area: contexts Repository information routing and discovery under contexts/ labels Jul 23, 2026
@keli-wen keli-wen self-assigned this Jul 23, 2026
keli-wen and others added 2 commits July 23, 2026 18:22
…/ link

The commit-body rule referenced github-writing.md via `../../../../contexts/dev/github-writing.md`, matching the repo's tested clickable-link convention but reading badly. commit.md is not test-bound to that link, so use a readable repo-root-relative backtick reference instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
…with data-mono)

Skill files referenced contexts pages with deep, fragile clickable links like `../../../../contexts/dev/github-writing.md`. The sister repo llmquant-data-mono instead uses repo-root-relative backtick references (`contexts/...`) from nested files, because a clean clickable repo-root link is only possible from a root-level file — GitHub resolves a bare relative link against the current file's directory, not the repo root, so a nested file needs the ugly `../` chain to stay clickable.

- SKILL.md and pull-request.md (both skill copies) now reference contexts pages as repo-root backtick paths (`contexts/README.md`, `contexts/dev/labels.md`, `contexts/dev/github-writing.md`) instead of `../../../` links. Root-level files (AGENTS.md) and sibling contexts pages keep their clean clickable links.
- tests/test_contexts.py: the three route tests now check that each source references the canonical guide in the form appropriate to its location — a backtick repo-root reference for nested skill files, a clickable link for root or sibling pages — and that the guide exists at the repo root, instead of asserting a specific deep relative link path.

verify.sh passes (426 passed, 85.65% coverage).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@keli-wen keli-wen changed the title feat(harness): PR-title CI lint, contexts/docs boundary, and commit-body wrap rule feat(harness): PR-title CI lint, contexts/docs boundary, commit-body rule, and repo-root-relative refs Jul 23, 2026
@keli-wen
keli-wen merged commit 30aed84 into master Jul 23, 2026
2 checks passed
@keli-wen
keli-wen deleted the feat/harness-close-134-pr-title-and-boundary branch July 23, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: contexts Repository information routing and discovery under contexts/ area: harness Contributor and agent controls, CI, hooks, skills, and rulesets type: feature Adds a new capability or observable behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(harness): agent-facing context map + convention-enforcing git hooks

1 participant